First Play Playback

Overview

First Play stations are trainer-influenced stations that play in a sequential order. They can only be viewed once per unique device by users accessing from within the United States and its territories.

A First Play station has a few additional features and potential pitfalls compared to a regular radio station. This guide will help you fully utilize all the features and avoid implementation issues. We recommend reading this guide in its entirety before beginning the implementation.

Initialization

Kotlin

new FeedAudioPlayer.Builder(getApplicationContext(), "demo", "demo").
setAvailabilityListener(new AvailabilityListener() {
            @Override
            public void onPlayerAvailable(@NonNull FeedAudioPlayer player) {
                // The player is now ready, save its reference for later use
                mPlayer = player;

                StationList list = player.getStationList()
                Station replayStation = list.getStationWithOption("uuid", "myuniqueReplaystationid")

            }

            @Override
            public void onPlayerUnavailable(@NonNull Exception e) {
                // The player is not available, either the user does not have a correct location
                // or the feed servers could not be reached. 

            }
        }).build();

Objective-C

[FMAudioPlayer setClientToken:@"demo" secret:@"demo"];

Listen for when the player is available.

FMAudioPlayer *player = [FMAudioPlayer sharedPlayer];
    [player whenAvailable:^{
        NSLog(@"Player is available");

        FMStation * station = [player.stationList getStationWithOptionKey:@"uuid" Value:@"my-unique-FirstPlay-station-id"];

    } notAvailable:^{
        NSLog(@"Player is not available");
    }];

The next step is to correctly set this station. This is done in the same way as with any radio station.

Kotlin

mPlayer.setActiveStation(station = station)
// Call play
mPlayer.play()

Objective-C

[[FMAudioPlayer sharedPlayer] setActiveStation:station];
[[FMAudioPlayer sharedPlayer] play];

Advance to Time in First Play Station

Also known as “start-at time” or “drop-in to time”

warning

Do not use advanceBy param for normal radio stations. For radio stations if you wish to pass a default value, it should be -1.

When playing a First Play station, a timestamp can be passed to the SDK to cause it to play music beginning at that offset. This enables, for example, a user who is starting a workout 8 minutes in to skip the first 8 minutes of music. This must be done while the station is being set for the first time. Once the First Play station has started playback on a device calling setActiveStation with withAdvance will return an error.

[[FMAudioPlayer sharedPlayer] setActiveStation:station withAdvance:@480];
// Call play
[[FMAudioPlayer sharedPlayer] play];

Kotlin

mPlayer.setActiveStation(station = station withCrossfade = false, advanceBy=480.0f)
// Call play
mPlayer.play()

Objective-C

[[FMAudioPlayer sharedPlayer] setActiveStation:station withAdvance:@480];
[[FMAudioPlayer sharedPlayer] play];

tip

You can only ‘advance’ into songs that have never started playback. So, once you hear 1 second of song A, the ‘advanceBy’ won’t return anything before song B

warning

Calling setActiveStation on the same station with and without the advanceBy parameter in quick succession can cause unexpected behavior.

tip

If a user starts a first play station and then leaves and comes back, you should still serve an alternate station to this user as it won't be possible to realign the user to the cadence.

If the station has already been fully played back for a given client_id, attempting to call play on the given station will trigger an outOfMusic() callback. We recommend you listen for this event using the OutOfMusicListener and switch to a backup station if the First Play station is outOfMusic.

tip

The Station object exposes single_play and last_played parameters for First Play and replay stations. These two parameters can help in identifying if a station has already been played back or not. You can check if the station has never been played by this user by calling hasNewMusic() on the station. If the result is true, this station can be successfully used for the associated workout while ensuring in order playback.